⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
feat(admin): add system status and test email endpoints
Tin04af5cc7d0c7
diff --git a/apps/api/src/admin/controllers/get-system-status.ts b/apps/api/src/admin/controllers/get-system-status.tsnew file mode 100644index 000000000..53b92fddb--- /dev/null+++ b/apps/api/src/admin/controllers/get-system-status.ts@@ -0,0 +1,47 @@+import { readAppVersion } from "../../app-version";+import { getLocalRealtimeStats } from "../../ws";+import { describeAuth } from "../system/describe-auth";+import { listIntegrationProviders } from "../system/list-integration-providers";+import { probeDatabase } from "../system/probe-database";+import { probeEmail } from "../system/probe-email";+import { probeRedis } from "../system/probe-redis";+import { probeStorage } from "../system/probe-storage";+import { realtimeStatus } from "../system/realtime-status";++const PROBE_TIMEOUT_MS = 3_000;++async function getSystemStatus() {+ const [database, redis, email, storage, integrations] = await Promise.all([+ probeDatabase(PROBE_TIMEOUT_MS),+ probeRedis(PROBE_TIMEOUT_MS),+ probeEmail(PROBE_TIMEOUT_MS),+ probeStorage(PROBE_TIMEOUT_MS),+ listIntegrationProviders(PROBE_TIMEOUT_MS),+ ]);+ const realtime = getLocalRealtimeStats();++ return {+ checkedAt: new Date().toISOString(),+ version: readAppVersion(),+ api: {+ status: "ok" as const,+ uptimeSeconds: Math.floor(process.uptime()),+ nodeVersion: process.version,+ },+ database,+ realtime: {+ status: realtimeStatus({+ adapter: realtime.adapter,+ redisStatus: redis.status,+ }),+ ...realtime,+ },+ redis,+ email,+ storage,+ auth: describeAuth(),+ integrations,+ };+}++export default getSystemStatus;diff --git a/apps/api/src/admin/controllers/send-test-email.ts b/apps/api/src/admin/controllers/send-test-email.tsnew file mode 100644index 000000000..0d47244a6--- /dev/null+++ b/apps/api/src/admin/controllers/send-test-email.ts@@ -0,0 +1,74 @@+import {+ getSmtpErrorDetails,+ isSmtpConfigured,+ sendTestEmail,+} from "@kaneo/email";+import { HTTPException } from "hono/http-exception";+import { ApiError } from "../../errors/api-error";+import { createAttemptLimiter } from "../system/attempt-limiter";++const testEmailLimiter = createAttemptLimiter({+ max: 5,+ windowMs: 10 * 60 * 1000,+});++function notConfigured() {+ return new ApiError(409, {+ message:+ "Email is not configured on this instance. Set SMTP_HOST and SMTP_FROM, then restart Kaneo.",+ code: "SMTP_NOT_CONFIGURED",+ });+}++type SendTestEmailInput = {+ userId: string;+ email: string;+};++/**+ * Send an SMTP test to the calling administrator's own address. There is no+ * recipient parameter, so this can't be used to relay mail to anyone else.+ */+async function sendAdminTestEmail({ userId, email }: SendTestEmailInput) {+ if (!isSmtpConfigured()) throw notConfigured();++ const decision = testEmailLimiter.take(userId);+ if (!decision.allowed) {+ throw new HTTPException(429, {+ res: Response.json(+ {+ message: `Too many test emails. Try again in ${decision.retryAfterSeconds} seconds.`,+ code: "RATE_LIMITED",+ },+ {+ status: 429,+ headers: { "Retry-After": String(decision.retryAfterSeconds) },+ },+ ),+ });+ }++ let result: Awaited<ReturnType<typeof sendTestEmail>>;+ try {+ result = await sendTestEmail(email, "Kaneo test email", {+ requestedAt: new Date(),+ });+ } catch (error) {+ const details = getSmtpErrorDetails(error);+ console.error("Error sending admin test email", details);+ const reason =+ "responseCode" in details+ ? `${details.code} ${details.responseCode}`+ : details.code;+ throw new ApiError(502, {+ message: `The mail server did not accept the test email (${reason}). Check the SMTP settings and the API logs.`,+ code: "SMTP_SEND_FAILED",+ });+ }++ if (!result.success) throw notConfigured();++ return { sent: true as const, to: email };+}++export default sendAdminTestEmail;diff --git a/apps/api/src/admin/index.ts b/apps/api/src/admin/index.tsindex 1f1d8b4f3..1856a92e5 100644--- a/apps/api/src/admin/index.ts+++ b/apps/api/src/admin/index.ts@@ -9,11 +9,13 @@ import { requireUserSession } from "../utils/require-user-session";import { adminAuditRequest } from "./audit/admin-audit-request";import addWorkspaceMember from "./controllers/add-workspace-member";import listAuditLog from "./controllers/list-audit-log";+import getSystemStatus from "./controllers/get-system-status";import listUsers from "./controllers/list-users";import listWorkspaceMembers from "./controllers/list-workspace-members";import listWorkspaceRoles from "./controllers/list-workspace-roles";import listWorkspaces from "./controllers/list-workspaces";import removeWorkspaceMember from "./controllers/remove-workspace-member";+import sendAdminTestEmail from "./controllers/send-test-email";import transferWorkspaceOwnership from "./controllers/transfer-workspace-ownership";import updateWorkspaceMemberRole from "./controllers/update-workspace-member-role";import adminUserRoutes from "./user-routes";@@ -34,6 +36,10 @@ import {transferAdminWorkspaceOwnershipBody,updateAdminWorkspaceMemberRoleBody,} from "./schema";+import {+ adminSystemStatusSchema,+ adminTestEmailResultSchema,+} from "./system/response";import { adminUserSecurityRoutes } from "./user-security-routes";const forbidden = errorResponse(@@ -236,6 +242,42 @@ const listAuditLogRoute = createRoute({},});+const getSystemStatusRoute = createRoute({+ method: "get",+ operationId: "getAdminSystemStatus",+ path: "/system",+ tags: ["Admin"],+ summary: "Get system status",+ description:+ "Check this API instance and the services it uses: version, uptime, database, WebSockets, Redis fan-out, SMTP, object storage, sign-in providers and integration providers. Each check gives up after a few seconds, so one unreachable service can't block the response. Only statuses, counts and short error categories are returned, never hosts, credentials or secrets. Requires an instance administrator session; API keys are rejected.",+ middleware: [requireUserSession, requireInstanceAdmin] as const,+ responses: {+ 200: jsonResponse("Status of this instance", adminSystemStatusSchema),+ 403: forbidden,+ },+});++const sendTestEmailRoute = createRoute({+ method: "post",+ operationId: "sendAdminTestEmail",+ path: "/system/test-email",+ tags: ["Admin"],+ summary: "Send a test email",+ description:+ "Send a test email to the calling administrator's own address to check the SMTP settings. There is no recipient parameter. Limited to 5 per administrator every 10 minutes on each API instance.",+ middleware: [requireUserSession, requireInstanceAdmin] as const,+ responses: {+ 200: jsonResponse(+ "The mail server accepted the test email",+ adminTestEmailResultSchema,+ ),+ 403: forbidden,+ 409: errorResponse("SMTP is not configured on this instance"),+ 429: errorResponse("Too many test emails; retry after Retry-After seconds"),+ 502: errorResponse("The mail server did not accept the test email"),+ },+});+const admin = apiRouter().openapi(listUsersRoute, async (c) =>c.json(await listUsers(c.req.valid("query")), 200),@@ -276,6 +318,18 @@ const admin = apiRouter()200,),)+ .openapi(getSystemStatusRoute, async (c) =>+ c.json(await getSystemStatus(), 200),+ )+ .openapi(sendTestEmailRoute, async (c) =>+ c.json(+ await sendAdminTestEmail({+ userId: c.get("userId"),+ email: c.get("userEmail"),+ }),+ 200,+ ),+ ).openapi(transferWorkspaceOwnershipRoute, async (c) =>c.json(await transferWorkspaceOwnership(diff --git a/apps/api/src/admin/system/attempt-limiter.test.ts b/apps/api/src/admin/system/attempt-limiter.test.tsnew file mode 100644index 000000000..4a151a340--- /dev/null+++ b/apps/api/src/admin/system/attempt-limiter.test.ts@@ -0,0 +1,43 @@+import { describe, expect, it } from "vite-plus/test";+import { createAttemptLimiter } from "./attempt-limiter";++describe("createAttemptLimiter", () => {+ it("allows up to the limit inside the window, then reports when to retry", () => {+ let now = 0;+ const limiter = createAttemptLimiter({+ max: 2,+ windowMs: 60_000,+ now: () => now,+ });++ expect(limiter.take("a")).toEqual({ allowed: true });+ now = 10_000;+ expect(limiter.take("a")).toEqual({ allowed: true });+ now = 15_000;+ expect(limiter.take("a")).toEqual({+ allowed: false,+ retryAfterSeconds: 45,+ });+ });++ it("counts each key separately", () => {+ const limiter = createAttemptLimiter({ max: 1, windowMs: 60_000 });+ expect(limiter.take("a").allowed).toBe(true);+ expect(limiter.take("b").allowed).toBe(true);+ expect(limiter.take("a").allowed).toBe(false);+ });++ it("allows again once the oldest attempt leaves the window", () => {+ let now = 0;+ const limiter = createAttemptLimiter({+ max: 1,+ windowMs: 1_000,+ now: () => now,+ });+ limiter.take("a");+ now = 999;+ expect(limiter.take("a").allowed).toBe(false);+ now = 1_000;+ expect(limiter.take("a").allowed).toBe(true);+ });+});diff --git a/apps/api/src/admin/system/attempt-limiter.ts b/apps/api/src/admin/system/attempt-limiter.tsnew file mode 100644index 000000000..56a144d15--- /dev/null+++ b/apps/api/src/admin/system/attempt-limiter.ts@@ -0,0 +1,44 @@+type AttemptLimiterOptions = {+ max: number;+ windowMs: number;+ now?: () => number;+};++export type AttemptDecision =+ | { allowed: true }+ | { allowed: false; retryAfterSeconds: number };++/**+ * A per-key sliding window kept in memory. Each API instance counts on its+ * own, which is enough to stop an administrator from flooding a mailbox.+ */+export function createAttemptLimiter({+ max,+ windowMs,+ now = Date.now,+}: AttemptLimiterOptions) {+ const attempts = new Map<string, number[]>();++ return {+ take(key: string): AttemptDecision {+ const current = now();+ const recent = (attempts.get(key) ?? []).filter(+ (at) => current - at < windowMs,+ );+ if (recent.length >= max) {+ attempts.set(key, recent);+ const oldest = recent[0] ?? current;+ return {+ allowed: false,+ retryAfterSeconds: Math.max(+ 1,+ Math.ceil((oldest + windowMs - current) / 1000),+ ),+ };+ }+ recent.push(current);+ attempts.set(key, recent);+ return { allowed: true };+ },+ };+}diff --git a/apps/api/src/admin/system/credential-set-status.test.ts b/apps/api/src/admin/system/credential-set-status.test.tsnew file mode 100644index 000000000..a2d6dfaea--- /dev/null+++ b/apps/api/src/admin/system/credential-set-status.test.ts@@ -0,0 +1,17 @@+import { describe, expect, it } from "vite-plus/test";+import { credentialSetStatus } from "./credential-set-status";++describe("credentialSetStatus", () => {+ it("is ok when every value is set", () => {+ expect(credentialSetStatus(["id", "secret"])).toBe("ok");+ });++ it("is not configured when nothing is set", () => {+ expect(credentialSetStatus([undefined, "", " "])).toBe("not_configured");+ });++ it("warns about a half-finished configuration", () => {+ expect(credentialSetStatus(["id", undefined])).toBe("warning");+ expect(credentialSetStatus(["", "secret", "key"])).toBe("warning");+ });+});diff --git a/apps/api/src/admin/system/credential-set-status.ts b/apps/api/src/admin/system/credential-set-status.tsnew file mode 100644index 000000000..88554db89--- /dev/null+++ b/apps/api/src/admin/system/credential-set-status.ts@@ -0,0 +1,13 @@+import type { ServiceStatus } from "./service-status";++/**+ * A feature that needs several settings is configured when all are present,+ * not configured when none are, and a configuration warning in between.+ */+export function credentialSetStatus(values: unknown[]): ServiceStatus {+ const present = values.filter(+ (value) => typeof value === "string" && value.trim() !== "",+ ).length;+ if (present === 0) return "not_configured";+ return present === values.length ? "ok" : "warning";+}diff --git a/apps/api/src/admin/system/describe-auth.ts b/apps/api/src/admin/system/describe-auth.tsnew file mode 100644index 000000000..3f6c42c57--- /dev/null+++ b/apps/api/src/admin/system/describe-auth.ts@@ -0,0 +1,84 @@+import getSettings from "../../utils/get-settings";+import { resolveFileSecret } from "../../utils/file-secret";+import { credentialSetStatus } from "./credential-set-status";+import type { ServiceStatus } from "./service-status";++export type AuthProvider = {+ id: "github" | "google" | "discord" | "custom";+ name: string;+ status: ServiceStatus;+};++function env(name: string) {+ return process.env[name]?.trim() ?? "";+}++// An unreadable *_FILE secret counts as missing instead of failing the page.+function customOAuthSecret() {+ try {+ return resolveFileSecret("CUSTOM_OAUTH_CLIENT_SECRET");+ } catch {+ return undefined;+ }+}++function customOAuthEndpoint() {+ if (env("CUSTOM_OAUTH_DISCOVERY_URL")) return "discovery";+ return env("CUSTOM_OAUTH_AUTHORIZATION_URL") && env("CUSTOM_OAUTH_TOKEN_URL")+ ? "manual"+ : "";+}++/**+ * Which sign-in paths this instance offers. Only booleans and display names+ * leave here: never client ids, secrets, or provider URLs.+ */+export function describeAuth() {+ const settings = getSettings();+ const providers: AuthProvider[] = [+ {+ id: "github",+ name: "GitHub",+ status: credentialSetStatus([+ env("GITHUB_OAUTH_CLIENT_ID") || env("GITHUB_CLIENT_ID"),+ env("GITHUB_OAUTH_CLIENT_SECRET") || env("GITHUB_CLIENT_SECRET"),+ ]),+ },+ {+ id: "google",+ name: "Google",+ status: credentialSetStatus([+ env("GOOGLE_CLIENT_ID"),+ env("GOOGLE_CLIENT_SECRET"),+ ]),+ },+ {+ id: "discord",+ name: "Discord",+ status: credentialSetStatus([+ env("DISCORD_CLIENT_ID"),+ env("DISCORD_CLIENT_SECRET"),+ ]),+ },+ {+ id: "custom",+ name: settings.customOAuthName ?? "OIDC",+ status: credentialSetStatus([+ env("CUSTOM_OAUTH_CLIENT_ID"),+ customOAuthSecret(),+ customOAuthEndpoint(),+ ]),+ },+ ];++ return {+ passwordSignIn: !settings.disableLoginForm,+ emailOtpSignIn: !settings.disableEmailOtpSignIn && settings.hasSmtp,+ registration: !settings.disableRegistration,+ passwordRegistration:+ !settings.disableRegistration && !settings.disablePasswordRegistration,+ guestAccess: settings.hasGuestAccess,+ workspaceCreation: !settings.disableWorkspaceCreation,+ providers,+ };+}diff --git a/apps/api/src/admin/system/list-integration-providers.ts b/apps/api/src/admin/system/list-integration-providers.tsnew file mode 100644index 000000000..47b76f660--- /dev/null+++ b/apps/api/src/admin/system/list-integration-providers.ts@@ -0,0 +1,62 @@+import { count, eq } from "drizzle-orm";+import db from "../../database";+import { integrationTable } from "../../database/schema";+import { integrationPlugins } from "../../plugins";+import { resolveGithubPrivateKey } from "../../plugins/github/utils/github-app";+import { credentialSetStatus } from "./credential-set-status";+import type { ServiceStatus } from "./service-status";+import { withTimeout } from "./with-timeout";++type IntegrationProvider = {+ type: string;+ name: string;+ status: ServiceStatus;+ requiresInstanceSetup: boolean;+ connectedProjects: number | null;+};++// Only the GitHub App is set up on the instance. Every other provider is+// connected per project with that project's own credentials.+function instanceSetupStatus(type: string): ServiceStatus | null {+ if (type !== "github") return null;+ return credentialSetStatus([+ process.env.GITHUB_APP_ID,+ process.env.GITHUB_WEBHOOK_SECRET,+ resolveGithubPrivateKey(),+ ]);+}++async function countConnectedProjects(timeoutMs: number) {+ try {+ const rows = await withTimeout(+ () =>+ db+ .select({ type: integrationTable.type, value: count() })+ .from(integrationTable)+ .where(eq(integrationTable.isActive, true))+ .groupBy(integrationTable.type),+ timeoutMs,+ );+ return new Map(rows.map((row) => [row.type, row.value]));+ } catch {+ return null;+ }+}++export async function listIntegrationProviders(+ timeoutMs: number,+): Promise<IntegrationProvider[]> {+ // Without the database the providers are still listed, with unknown counts.+ const connected = await countConnectedProjects(timeoutMs);++ return integrationPlugins.map(({ type, name }) => {+ const setup = instanceSetupStatus(type);+ return {+ type,+ name,+ status: setup ?? "ok",+ requiresInstanceSetup: setup !== null,+ connectedProjects: connected ? (connected.get(type) ?? 0) : null,+ };+ });+}diff --git a/apps/api/src/admin/system/probe-database.ts b/apps/api/src/admin/system/probe-database.tsnew file mode 100644index 000000000..2a3da646e--- /dev/null+++ b/apps/api/src/admin/system/probe-database.ts@@ -0,0 +1,57 @@+import { sql } from "drizzle-orm";+import db from "../../database";+import { safeErrorCode } from "./safe-error-code";+import type { ServiceStatus } from "./service-status";+import { withTimeout } from "./with-timeout";++type DatabaseProbe = {+ status: ServiceStatus;+ serverVersion: string | null;+ latencyMs: number | null;+ migrationsApplied: number | null;+ errorCode: string | null;+};++async function countAppliedMigrations(timeoutMs: number) {+ try {+ const result = await withTimeout(+ () =>+ db.execute<{ applied: number }>(+ sql`select count(*)::int as applied from drizzle.__drizzle_migrations`,+ ),+ timeoutMs,+ );+ return result.rows[0]?.applied ?? null;+ } catch {+ return null;+ }+}++export async function probeDatabase(timeoutMs: number): Promise<DatabaseProbe> {+ const started = performance.now();+ try {+ const result = await withTimeout(+ () =>+ db.execute<{ version: string }>(+ sql`select current_setting('server_version') as version`,+ ),+ timeoutMs,+ );+ const latencyMs = Math.round(performance.now() - started);+ return {+ status: "ok",+ serverVersion: result.rows[0]?.version ?? null,+ latencyMs,+ migrationsApplied: await countAppliedMigrations(timeoutMs),+ errorCode: null,+ };+ } catch (error) {+ return {+ status: "down",+ serverVersion: null,+ latencyMs: null,+ migrationsApplied: null,+ errorCode: safeErrorCode(error),+ };+ }+}diff --git a/apps/api/src/admin/system/probe-email.ts b/apps/api/src/admin/system/probe-email.tsnew file mode 100644index 000000000..d70f1c7fe--- /dev/null+++ b/apps/api/src/admin/system/probe-email.ts@@ -0,0 +1,33 @@+import { verifySmtpConnection } from "@kaneo/email";+import { safeErrorCode } from "./safe-error-code";+import type { ServiceStatus } from "./service-status";+import { withTimeout } from "./with-timeout";++type EmailProbe = {+ status: ServiceStatus;+ configured: boolean;+ errorCode: string | null;+};++export async function probeEmail(timeoutMs: number): Promise<EmailProbe> {+ try {+ // nodemailer bounds each phase itself; the outer limit covers DNS.+ const result = await withTimeout(+ () => verifySmtpConnection(timeoutMs),+ timeoutMs + 500,+ );+ if (result.status === "not_configured") {+ return { status: "not_configured", configured: false, errorCode: null };+ }+ if (result.status === "ok") {+ return { status: "ok", configured: true, errorCode: null };+ }+ return { status: "down", configured: true, errorCode: result.code };+ } catch (error) {+ return {+ status: "down",+ configured: true,+ errorCode: safeErrorCode(error),+ };+ }+}diff --git a/apps/api/src/admin/system/probe-redis.ts b/apps/api/src/admin/system/probe-redis.tsnew file mode 100644index 000000000..c8380c736--- /dev/null+++ b/apps/api/src/admin/system/probe-redis.ts@@ -0,0 +1,32 @@+import { getRedisPub, isRedisConfigured, resolveRedisMode } from "../../redis";+import { safeErrorCode } from "./safe-error-code";+import type { ServiceStatus } from "./service-status";+import { withTimeout } from "./with-timeout";++type RedisProbe = {+ status: ServiceStatus;+ mode: "standalone" | "sentinel" | "cluster" | null;+ errorCode: string | null;+};++// Redis only fans realtime events out across API instances. A single+// instance runs without it, so "not configured" is a healthy answer.+export async function probeRedis(timeoutMs: number): Promise<RedisProbe> {+ if (!isRedisConfigured()) {+ return { status: "not_configured", mode: null, errorCode: null };+ }++ let mode: RedisProbe["mode"];+ try {+ mode = resolveRedisMode().mode;+ } catch {+ return { status: "down", mode: null, errorCode: "INVALID_CONFIG" };+ }++ try {+ await withTimeout(() => getRedisPub().ping(), timeoutMs);+ return { status: "ok", mode, errorCode: null };+ } catch (error) {+ return { status: "down", mode, errorCode: safeErrorCode(error) };+ }+}diff --git a/apps/api/src/admin/system/probe-storage.test.ts b/apps/api/src/admin/system/probe-storage.test.tsnew file mode 100644index 000000000..dacf5a0bf--- /dev/null+++ b/apps/api/src/admin/system/probe-storage.test.ts@@ -0,0 +1,21 @@+import { describe, expect, it } from "vite-plus/test";+import { storageFailureStatus } from "./probe-storage";++describe("storageFailureStatus", () => {+ it("warns when the bucket refuses to be listed", () => {+ expect(storageFailureStatus({ $metadata: { httpStatusCode: 403 } })).toBe(+ "warning",+ );+ });++ it("is down for a missing bucket or an unreachable endpoint", () => {+ expect(storageFailureStatus({ $metadata: { httpStatusCode: 404 } })).toBe(+ "down",+ );+ expect(+ storageFailureStatus(+ Object.assign(new Error(), { code: "ECONNREFUSED" }),+ ),+ ).toBe("down");+ });+});diff --git a/apps/api/src/admin/system/probe-storage.ts b/apps/api/src/admin/system/probe-storage.tsnew file mode 100644index 000000000..6d10bf056--- /dev/null+++ b/apps/api/src/admin/system/probe-storage.ts@@ -0,0 +1,52 @@+import { headStorageBucket, isStorageConfigured } from "../../storage/s3";+import { safeErrorCode } from "./safe-error-code";+import type { ServiceStatus } from "./service-status";+import { withTimeout } from "./with-timeout";++type StorageProbe = {+ status: ServiceStatus;+ configured: boolean;+ errorCode: string | null;+};++const STORAGE_ENV = [+ "S3_ENDPOINT",+ "S3_BUCKET",+ "S3_ACCESS_KEY_ID",+ "S3_SECRET_ACCESS_KEY",+];++function httpStatus(error: unknown) {+ const status = (error as { $metadata?: { httpStatusCode?: unknown } })+ ?.$metadata?.httpStatusCode;+ return typeof status === "number" ? status : undefined;+}++/**+ * A 403 means the bucket answered but these credentials may not list it,+ * which upload-only IAM policies do on purpose. Report that as a warning.+ */+export function storageFailureStatus(error: unknown): ServiceStatus {+ return httpStatus(error) === 403 ? "warning" : "down";+}++export async function probeStorage(timeoutMs: number): Promise<StorageProbe> {+ if (!isStorageConfigured()) {+ const partlySet = STORAGE_ENV.some((name) => process.env[name]?.trim());+ return partlySet+ ? { status: "warning", configured: false, errorCode: "INCOMPLETE_CONFIG" }+ : { status: "not_configured", configured: false, errorCode: null };+ }++ try {+ await withTimeout((signal) => headStorageBucket(signal), timeoutMs);+ return { status: "ok", configured: true, errorCode: null };+ } catch (error) {+ const status = httpStatus(error);+ return {+ status: storageFailureStatus(error),+ configured: true,+ errorCode: status ? `HTTP_${status}` : safeErrorCode(error),+ };+ }+}diff --git a/apps/api/src/admin/system/realtime-status.test.ts b/apps/api/src/admin/system/realtime-status.test.tsnew file mode 100644index 000000000..a62a92a63--- /dev/null+++ b/apps/api/src/admin/system/realtime-status.test.ts@@ -0,0 +1,26 @@+import { describe, expect, it } from "vite-plus/test";+import { realtimeStatus } from "./realtime-status";++describe("realtimeStatus", () => {+ it("is healthy on a single instance without Redis", () => {+ expect(+ realtimeStatus({ adapter: "in-memory", redisStatus: "not_configured" }),+ ).toBe("ok");+ });++ it("is healthy when Redis fan-out answers", () => {+ expect(realtimeStatus({ adapter: "redis", redisStatus: "ok" })).toBe("ok");+ });++ it("warns when Redis fan-out is down but local sockets still work", () => {+ expect(realtimeStatus({ adapter: "redis", redisStatus: "down" })).toBe(+ "warning",+ );+ });++ it("is down before the WebSocket adapter starts", () => {+ expect(+ realtimeStatus({ adapter: null, redisStatus: "not_configured" }),+ ).toBe("down");+ });+});diff --git a/apps/api/src/admin/system/realtime-status.ts b/apps/api/src/admin/system/realtime-status.tsnew file mode 100644index 000000000..30812e684--- /dev/null+++ b/apps/api/src/admin/system/realtime-status.ts@@ -0,0 +1,19 @@+import type { ServiceStatus } from "./service-status";++type RealtimeStatusInput = {+ adapter: "redis" | "in-memory" | null;+ redisStatus: ServiceStatus;+};++/**+ * Sockets on this instance keep working while Redis is down; only delivery+ * to clients on other instances stops. Without an adapter nothing is sent.+ */+export function realtimeStatus({+ adapter,+ redisStatus,+}: RealtimeStatusInput): ServiceStatus {+ if (adapter === null) return "down";+ if (adapter === "redis" && redisStatus !== "ok") return "warning";+ return "ok";+}diff --git a/apps/api/src/admin/system/response.ts b/apps/api/src/admin/system/response.tsnew file mode 100644index 000000000..78ce92854--- /dev/null+++ b/apps/api/src/admin/system/response.ts@@ -0,0 +1,96 @@+import { z } from "../../openapi";+import { serviceStatusSchema } from "./service-status";++const errorCode = z.string().nullable().openapi({+ description:+ "Short failure category such as TIMEOUT, ECONNREFUSED or HTTP_403. Never contains hosts, credentials or server messages.",+});++export const adminSystemStatusSchema = z+ .object({+ checkedAt: z.string().openapi({ format: "date-time" }),+ version: z.string().nullable().openapi({+ description: "Kaneo release version of this API instance.",+ }),+ api: z.object({+ status: serviceStatusSchema,+ uptimeSeconds: z.number().int(),+ nodeVersion: z.string(),+ }),+ database: z.object({+ status: serviceStatusSchema,+ serverVersion: z.string().nullable(),+ latencyMs: z.number().int().nullable(),+ migrationsApplied: z.number().int().nullable(),+ errorCode,+ }),+ realtime: z.object({+ status: serviceStatusSchema,+ adapter: z.enum(["in-memory", "redis"]).nullable().openapi({+ description:+ "How events reach WebSocket clients: in-memory for a single instance, redis to fan out across instances. Null before WebSockets start.",+ }),+ connections: z.number().int().openapi({+ description: "Open WebSocket connections on this API instance.",+ }),+ connectedUsers: z.number().int().openapi({+ description:+ "Distinct people with an open connection to this instance.",+ }),+ }),+ redis: z.object({+ status: serviceStatusSchema,+ mode: z.enum(["standalone", "sentinel", "cluster"]).nullable(),+ errorCode,+ }),+ email: z.object({+ status: serviceStatusSchema,+ configured: z.boolean(),+ errorCode,+ }),+ storage: z.object({+ status: serviceStatusSchema,+ configured: z.boolean(),+ errorCode,+ }),+ auth: z.object({+ passwordSignIn: z.boolean(),+ emailOtpSignIn: z.boolean(),+ registration: z.boolean(),+ passwordRegistration: z.boolean(),+ guestAccess: z.boolean(),+ workspaceCreation: z.boolean(),+ providers: z.array(+ z.object({+ id: z.enum(["github", "google", "discord", "custom"]),+ name: z.string(),+ status: serviceStatusSchema,+ }),+ ),+ }),+ integrations: z.array(+ z.object({+ type: z.string(),+ name: z.string(),+ status: serviceStatusSchema,+ requiresInstanceSetup: z.boolean().openapi({+ description:+ "Whether the provider needs instance settings. Others are connected per project.",+ }),+ connectedProjects: z.number().int().nullable().openapi({+ description:+ "Projects with an active connection to this provider. Null when the database could not be read.",+ }),+ }),+ ),+ })+ .openapi("AdminSystemStatus");++export const adminTestEmailResultSchema = z+ .object({+ sent: z.literal(true),+ to: z.string().openapi({+ description: "The administrator's own address, the only recipient.",+ }),+ })+ .openapi("AdminTestEmailResult");diff --git a/apps/api/src/admin/system/safe-error-code.test.ts b/apps/api/src/admin/system/safe-error-code.test.tsnew file mode 100644index 000000000..3177df468--- /dev/null+++ b/apps/api/src/admin/system/safe-error-code.test.ts@@ -0,0 +1,31 @@+import { describe, expect, it } from "vite-plus/test";+import { safeErrorCode } from "./safe-error-code";+import { ProbeTimeoutError } from "./with-timeout";++describe("safeErrorCode", () => {+ it("names timeouts", () => {+ expect(safeErrorCode(new ProbeTimeoutError())).toBe("TIMEOUT");+ });++ it("keeps driver codes and specific error names", () => {+ expect(+ safeErrorCode(Object.assign(new Error("x"), { code: "ECONNREFUSED" })),+ ).toBe("ECONNREFUSED");+ expect(+ safeErrorCode(Object.assign(new Error("x"), { code: "28P01" })),+ ).toBe("28P01");+ const notFound = new Error("bucket missing");+ notFound.name = "NoSuchBucket";+ expect(safeErrorCode(notFound)).toBe("NoSuchBucket");+ });++ it("never returns the message or malformed codes", () => {+ const error = Object.assign(+ new Error("password authentication failed for user admin"),+ { code: "connect to redis://:hunter2@cache:6379 failed" },+ );+ expect(safeErrorCode(error)).toBe("UNKNOWN");+ expect(safeErrorCode("redis://:hunter2@cache")).toBe("UNKNOWN");+ expect(safeErrorCode(null)).toBe("UNKNOWN");+ });+});diff --git a/apps/api/src/admin/system/safe-error-code.ts b/apps/api/src/admin/system/safe-error-code.tsnew file mode 100644index 000000000..4624851a3--- /dev/null+++ b/apps/api/src/admin/system/safe-error-code.ts@@ -0,0 +1,19 @@+import { ProbeTimeoutError } from "./with-timeout";++const CODE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;++/**+ * A short identifier for a failed probe. Driver messages can include hosts,+ * user names or credentials, so only well-formed codes and error names are+ * kept; anything else becomes UNKNOWN.+ */+export function safeErrorCode(error: unknown): string {+ if (error instanceof ProbeTimeoutError) return "TIMEOUT";+ if (typeof error !== "object" || error === null) return "UNKNOWN";+ const { code, name } = error as { code?: unknown; name?: unknown };+ if (typeof code === "string" && CODE_PATTERN.test(code)) return code;+ if (typeof name === "string" && name !== "Error" && CODE_PATTERN.test(name)) {+ return name;+ }+ return "UNKNOWN";+}diff --git a/apps/api/src/admin/system/service-status.ts b/apps/api/src/admin/system/service-status.tsnew file mode 100644index 000000000..419adbf94--- /dev/null+++ b/apps/api/src/admin/system/service-status.ts@@ -0,0 +1,15 @@+import { z } from "../../openapi";++export const SERVICE_STATUSES = [+ "ok",+ "warning",+ "not_configured",+ "down",+] as const;++export type ServiceStatus = (typeof SERVICE_STATUSES)[number];++export const serviceStatusSchema = z.enum(SERVICE_STATUSES).openapi({+ description:+ "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable.",+});diff --git a/apps/api/src/admin/system/with-timeout.test.ts b/apps/api/src/admin/system/with-timeout.test.tsnew file mode 100644index 000000000..22386ec6d--- /dev/null+++ b/apps/api/src/admin/system/with-timeout.test.ts@@ -0,0 +1,32 @@+import { describe, expect, it } from "vite-plus/test";+import { ProbeTimeoutError, withTimeout } from "./with-timeout";++describe("withTimeout", () => {+ it("returns the result when the work finishes in time", async () => {+ await expect(withTimeout(async () => "ok", 50)).resolves.toBe("ok");+ });++ it("passes the work's own error through", async () => {+ await expect(+ withTimeout(async () => {+ throw new Error("boom");+ }, 50),+ ).rejects.toThrow("boom");+ });++ it("rejects and aborts the work when it takes too long", async () => {+ let aborted = false;+ const result = withTimeout(+ (signal) =>+ new Promise((_, reject) => {+ signal.addEventListener("abort", () => {+ aborted = true;+ reject(new Error("late failure"));+ });+ }),+ 10,+ );+ await expect(result).rejects.toBeInstanceOf(ProbeTimeoutError);+ expect(aborted).toBe(true);+ });+});diff --git a/apps/api/src/admin/system/with-timeout.ts b/apps/api/src/admin/system/with-timeout.tsnew file mode 100644index 000000000..f89f77d5e--- /dev/null+++ b/apps/api/src/admin/system/with-timeout.ts@@ -0,0 +1,30 @@+export class ProbeTimeoutError extends Error {+ constructor() {+ super("Timed out");+ this.name = "ProbeTimeoutError";+ }+}++/**+ * Resolve with `work`, or reject with ProbeTimeoutError after `ms`. The+ * abandoned promise keeps running, so its later rejection is swallowed here+ * instead of surfacing as an unhandled rejection.+ */+export function withTimeout<T>(+ work: (signal: AbortSignal) => Promise<T>,+ ms: number,+): Promise<T> {+ const controller = new AbortController();+ let timer: ReturnType<typeof setTimeout> | undefined;+ const pending = work(controller.signal);+ pending.catch(() => {});+ const timeout = new Promise<never>((_, reject) => {+ timer = setTimeout(() => {+ // Settle first: aborting can reject `work` synchronously, and that+ // abort error must not win the race over the timeout.+ reject(new ProbeTimeoutError());+ controller.abort();+ }, ms);+ });+ return Promise.race([pending, timeout]).finally(() => clearTimeout(timer));+}diff --git a/apps/api/src/app-version.ts b/apps/api/src/app-version.tsnew file mode 100644index 000000000..161479196--- /dev/null+++ b/apps/api/src/app-version.ts@@ -0,0 +1,24 @@+import { readFileSync } from "node:fs";++/**+ * The release version from the root package.json. This file and the bundled+ * dist/index.js both sit one level below apps/api, so the same relative path+ * works in development and in the Docker image.+ */+function loadAppVersion(): string | null {+ try {+ const pkg = JSON.parse(+ readFileSync(new URL("../../../package.json", import.meta.url), "utf8"),+ );+ return typeof pkg.version === "string" ? pkg.version : null;+ } catch {+ return null;+ }+}++let cached: { version: string | null } | undefined;++export function readAppVersion(): string | null {+ cached ??= { version: loadAppVersion() };+ return cached.version;+}diff --git a/apps/api/src/instrument.ts b/apps/api/src/instrument.tsindex b368c2cd9..fa871ab3a 100644--- a/apps/api/src/instrument.ts+++ b/apps/api/src/instrument.ts@@ -1,6 +1,6 @@-import { readFileSync } from "node:fs";import * as Sentry from "@sentry/node";import { nodeProfilingIntegration } from "@sentry/profiling-node";+import { readAppVersion } from "./app-version";import { isSensitiveOutboundRequest } from "./utils/sensitive-outbound";function parseSampleRate(value: string | undefined) {@@ -14,23 +14,12 @@ const profilesSampleRate = parseSampleRate(process.env.SENTRY_PROFILES_SAMPLE_RATE,);-function readAppVersion() {- try {- const pkg = JSON.parse(- readFileSync(new URL("../../../package.json", import.meta.url), "utf8"),- );- return typeof pkg.version === "string" ? pkg.version : undefined;- } catch {- return undefined;- }-}-if (process.env.SENTRY_DSN) {Sentry.init({dsn: process.env.SENTRY_DSN,environment:process.env.SENTRY_ENVIRONMENT ?? process.env.NODE_ENV ?? "production",- release: process.env.SENTRY_RELEASE ?? readAppVersion(),+ release: process.env.SENTRY_RELEASE ?? readAppVersion() ?? undefined,dataCollection: {userInfo: false,cookies: false,diff --git a/apps/api/src/plugins/index.ts b/apps/api/src/plugins/index.tsindex f05e8695e..fb46fca39 100644--- a/apps/api/src/plugins/index.ts+++ b/apps/api/src/plugins/index.ts@@ -8,17 +8,23 @@ import { initializeEventSubscriptions, registerPlugin } from "./registry";import { slackPlugin } from "./slack";import { telegramPlugin } from "./telegram";+export const integrationPlugins = [+ githubPlugin,+ giteaPlugin,+ gitlabPlugin,+ slackPlugin,+ mattermostPlugin,+ discordPlugin,+ genericWebhookPlugin,+ telegramPlugin,+];+export function initializePlugins() {console.log("Initializing plugins...");- registerPlugin(githubPlugin);- registerPlugin(giteaPlugin);- registerPlugin(gitlabPlugin);- registerPlugin(slackPlugin);- registerPlugin(mattermostPlugin);- registerPlugin(discordPlugin);- registerPlugin(genericWebhookPlugin);- registerPlugin(telegramPlugin);+ for (const plugin of integrationPlugins) {+ registerPlugin(plugin);+ }initializeGitHubPlugin();initializeEventSubscriptions();diff --git a/apps/api/src/storage/s3.ts b/apps/api/src/storage/s3.tsindex b22191288..8d04d5ab8 100644--- a/apps/api/src/storage/s3.ts+++ b/apps/api/src/storage/s3.ts@@ -3,6 +3,7 @@ import {CopyObjectCommand,DeleteObjectCommand,GetObjectCommand,+ HeadBucketCommand,type HeadObjectCommandOutput,PutObjectCommand,S3Client,@@ -495,6 +496,17 @@ export function isStorageConfigured() {}}+/** Check that the bucket answers with the configured credentials. */+export async function headStorageBucket(abortSignal: AbortSignal) {+ const config = getStorageConfig();+ await getClient(config).send(+ new HeadBucketCommand({ Bucket: config.bucket }),+ {+ abortSignal,+ },+ );+}+export function assertTaskImageKeyMatchesContext(key: string,context: Omit<TaskImageUploadContext, "filename" | "contentType">,diff --git a/apps/api/src/ws/index.ts b/apps/api/src/ws/index.tsindex 49539dd56..4a61209ab 100644--- a/apps/api/src/ws/index.ts+++ b/apps/api/src/ws/index.ts@@ -249,6 +249,33 @@ const projectBroadcastTimeouts = new Map<let adapter: BroadcastAdapter | null = null;+/** Open sockets on this API instance, for the admin system page. */+export function getLocalRealtimeStats() {+ const users = new Set<string>();+ let connections = 0;+ for (const [userId, sockets] of userConnections) {+ if (sockets.size === 0) continue;+ users.add(userId);+ connections += sockets.size;+ }+ for (const sockets of projectConnections.values()) {+ for (const socket of sockets) {+ users.add(socket.userId);+ connections += 1;+ }+ }+ return {+ adapter:+ adapter === null+ ? null+ : adapter instanceof RedisBroadcastAdapter+ ? ("redis" as const)+ : ("in-memory" as const),+ connections,+ connectedUsers: users.size,+ };+}+// --- Subscribe to incoming broadcasts and deliver to local connections ---export async function initializeWebSocketAdapter() {if (adapter) return;diff --git a/apps/docs/openapi.json b/apps/docs/openapi.jsonindex d7cabdc6c..96cbe27ae 100644--- a/apps/docs/openapi.json+++ b/apps/docs/openapi.json@@ -5619,6 +5619,375 @@"joinedAt"]},+ "AdminSystemStatus": {+ "type": "object",+ "properties": {+ "checkedAt": {+ "type": "string",+ "format": "date-time"+ },+ "version": {+ "type": [+ "string",+ "null"+ ],+ "description": "Kaneo release version of this API instance."+ },+ "api": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "enum": [+ "ok",+ "warning",+ "not_configured",+ "down"+ ],+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."+ },+ "uptimeSeconds": {+ "type": "integer"+ },+ "nodeVersion": {+ "type": "string"+ }+ },+ "required": [+ "status",+ "uptimeSeconds",+ "nodeVersion"+ ]+ },+ "database": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "enum": [+ "ok",+ "warning",+ "not_configured",+ "down"+ ],+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."+ },+ "serverVersion": {+ "type": [+ "string",+ "null"+ ]+ },+ "latencyMs": {+ "type": [+ "integer",+ "null"+ ]+ },+ "migrationsApplied": {+ "type": [+ "integer",+ "null"+ ]+ },+ "errorCode": {+ "type": [+ "string",+ "null"+ ],+ "description": "Short failure category such as TIMEOUT, ECONNREFUSED or HTTP_403. Never contains hosts, credentials or server messages."+ }+ },+ "required": [+ "status",+ "serverVersion",+ "latencyMs",+ "migrationsApplied",+ "errorCode"+ ]+ },+ "realtime": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "enum": [+ "ok",+ "warning",+ "not_configured",+ "down"+ ],+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."+ },+ "adapter": {+ "type": [+ "string",+ "null"+ ],+ "enum": [+ "in-memory",+ "redis",+ null+ ],+ "description": "How events reach WebSocket clients: in-memory for a single instance, redis to fan out across instances. Null before WebSockets start."+ },+ "connections": {+ "type": "integer",+ "description": "Open WebSocket connections on this API instance."+ },+ "connectedUsers": {+ "type": "integer",+ "description": "Distinct people with an open connection to this instance."+ }+ },+ "required": [+ "status",+ "adapter",+ "connections",+ "connectedUsers"+ ]+ },+ "redis": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "enum": [+ "ok",+ "warning",+ "not_configured",+ "down"+ ],+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."+ },+ "mode": {+ "type": [+ "string",+ "null"+ ],+ "enum": [+ "standalone",+ "sentinel",+ "cluster",+ null+ ]+ },+ "errorCode": {+ "type": [+ "string",+ "null"+ ],+ "description": "Short failure category such as TIMEOUT, ECONNREFUSED or HTTP_403. Never contains hosts, credentials or server messages."+ }+ },+ "required": [+ "status",+ "mode",+ "errorCode"+ ]+ },+ "email": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "enum": [+ "ok",+ "warning",+ "not_configured",+ "down"+ ],+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."+ },+ "configured": {+ "type": "boolean"+ },+ "errorCode": {+ "type": [+ "string",+ "null"+ ],+ "description": "Short failure category such as TIMEOUT, ECONNREFUSED or HTTP_403. Never contains hosts, credentials or server messages."+ }+ },+ "required": [+ "status",+ "configured",+ "errorCode"+ ]+ },+ "storage": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "enum": [+ "ok",+ "warning",+ "not_configured",+ "down"+ ],+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."+ },+ "configured": {+ "type": "boolean"+ },+ "errorCode": {+ "type": [+ "string",+ "null"+ ],+ "description": "Short failure category such as TIMEOUT, ECONNREFUSED or HTTP_403. Never contains hosts, credentials or server messages."+ }+ },+ "required": [+ "status",+ "configured",+ "errorCode"+ ]+ },+ "auth": {+ "type": "object",+ "properties": {+ "passwordSignIn": {+ "type": "boolean"+ },+ "emailOtpSignIn": {+ "type": "boolean"+ },+ "registration": {+ "type": "boolean"+ },+ "passwordRegistration": {+ "type": "boolean"+ },+ "guestAccess": {+ "type": "boolean"+ },+ "workspaceCreation": {+ "type": "boolean"+ },+ "providers": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "enum": [+ "github",+ "google",+ "discord",+ "custom"+ ]+ },+ "name": {+ "type": "string"+ },+ "status": {+ "type": "string",+ "enum": [+ "ok",+ "warning",+ "not_configured",+ "down"+ ],+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."+ }+ },+ "required": [+ "id",+ "name",+ "status"+ ]+ }+ }+ },+ "required": [+ "passwordSignIn",+ "emailOtpSignIn",+ "registration",+ "passwordRegistration",+ "guestAccess",+ "workspaceCreation",+ "providers"+ ]+ },+ "integrations": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "type": {+ "type": "string"+ },+ "name": {+ "type": "string"+ },+ "status": {+ "type": "string",+ "enum": [+ "ok",+ "warning",+ "not_configured",+ "down"+ ],+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."+ },+ "requiresInstanceSetup": {+ "type": "boolean",+ "description": "Whether the provider needs instance settings. Others are connected per project."+ },+ "connectedProjects": {+ "type": [+ "integer",+ "null"+ ],+ "description": "Projects with an active connection to this provider. Null when the database could not be read."+ }+ },+ "required": [+ "type",+ "name",+ "status",+ "requiresInstanceSetup",+ "connectedProjects"+ ]+ }+ }+ },+ "required": [+ "checkedAt",+ "version",+ "api",+ "database",+ "realtime",+ "redis",+ "email",+ "storage",+ "auth",+ "integrations"+ ]+ },+ "AdminTestEmailResult": {+ "type": "object",+ "properties": {+ "sent": {+ "type": "boolean",+ "enum": [+ true+ ]+ },+ "to": {+ "type": "string",+ "description": "The administrator's own address, the only recipient."+ }+ },+ "required": [+ "sent",+ "to"+ ]+ },"AdminAuditLog": {"type": "object","properties": {@@ -25236,6 +25605,123 @@}}},+ "/admin/system": {+ "get": {+ "operationId": "getAdminSystemStatus",+ "tags": [+ "Admin"+ ],+ "summary": "Get system status",+ "description": "Check this API instance and the services it uses: version, uptime, database, WebSockets, Redis fan-out, SMTP, object storage, sign-in providers and integration providers. Each check gives up after a few seconds, so one unreachable service can't block the response. Only statuses, counts and short error categories are returned, never hosts, credentials or secrets. Requires an instance administrator session; API keys are rejected.",+ "responses": {+ "200": {+ "description": "Status of this instance",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AdminSystemStatus"+ }+ }+ }+ },+ "401": {+ "description": "Missing or invalid credentials",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApiError"+ }+ }+ }+ },+ "403": {+ "description": "The caller is not an instance administrator or is authenticated with an API key",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApiError"+ }+ }+ }+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ }+ }+ }+ },+ "/admin/system/test-email": {+ "post": {+ "operationId": "sendAdminTestEmail",+ "tags": [+ "Admin"+ ],+ "summary": "Send a test email",+ "description": "Send a test email to the calling administrator's own address to check the SMTP settings. There is no recipient parameter. Limited to 5 per administrator every 10 minutes on each API instance.",+ "responses": {+ "200": {+ "description": "The mail server accepted the test email",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AdminTestEmailResult"+ }+ }+ }+ },+ "401": {+ "description": "Missing or invalid credentials",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApiError"+ }+ }+ }+ },+ "403": {+ "description": "The caller is not an instance administrator or is authenticated with an API key",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApiError"+ }+ }+ }+ },+ "409": {+ "description": "SMTP is not configured on this instance",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApiError"+ }+ }+ }+ },+ "429": {+ "description": "Too many test emails; retry after Retry-After seconds",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApiError"+ }+ }+ }+ },+ "502": {+ "description": "The mail server did not accept the test email",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApiError"+ }+ }+ }+ }+ }+ }+ },"/admin/workspaces/{workspaceId}/owner": {"put": {"operationId": "transferAdminWorkspaceOwnership",diff --git a/tests/api-integration/admin-system-status.test.ts b/tests/api-integration/admin-system-status.test.tsnew file mode 100644index 000000000..8cc852e6e--- /dev/null+++ b/tests/api-integration/admin-system-status.test.ts@@ -0,0 +1,370 @@+import { createHash, randomUUID } from "node:crypto";+import { readFileSync } from "node:fs";+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";+import db, { schema } from "../../apps/api/src/database";+import { mockAnonymousSession, mockAuthenticatedSession } from "./helpers/auth";+import { createInstanceAdmin } from "./helpers/admin/create-instance-admin";+import { resetTestDatabase } from "./helpers/database";+import { createRestrictedWorkspace } from "./helpers/project-access/create-restricted-workspace";+import { projectAccessApi } from "./helpers/project-access/project-access-api";++const smtp = vi.hoisted(() => ({+ configured: vi.fn(() => false),+ send: vi.fn(async () => ({ success: true })),+ verify: vi.fn(async () => ({ status: "not_configured" })),+}));++const redis = vi.hoisted(() => ({+ ping: vi.fn(async () => "PONG"),+}));++vi.mock("@kaneo/email", async (importOriginal) => ({+ ...(await importOriginal<Record<string, unknown>>()),+ isSmtpConfigured: smtp.configured,+ sendTestEmail: smtp.send,+ verifySmtpConnection: smtp.verify,+}));++// Keeps the real configuration parsing but never opens a Redis connection.+vi.mock("../../apps/api/src/redis", async (importOriginal) => ({+ ...(await importOriginal<Record<string, unknown>>()),+ getRedisPub: () => ({ ping: redis.ping }),+}));++beforeEach(async () => {+ await resetTestDatabase();+ smtp.configured.mockReset().mockReturnValue(false);+ smtp.send.mockReset().mockResolvedValue({ success: true });+ smtp.verify.mockReset().mockResolvedValue({ status: "not_configured" });+ redis.ping.mockReset().mockResolvedValue("PONG");+});++type SystemStatus = {+ version: string | null;+ api: { status: string; uptimeSeconds: number };+ database: {+ status: string;+ serverVersion: string | null;+ migrationsApplied: number | null;+ };+ realtime: { status: string; connections: number };+ redis: { status: string; mode: string | null; errorCode: string | null };+ email: { status: string; configured: boolean; errorCode: string | null };+ storage: { status: string; configured: boolean; errorCode: string | null };+ auth: {+ passwordSignIn: boolean;+ registration: boolean;+ providers: { id: string; name: string; status: string }[];+ };+ integrations: {+ type: string;+ status: string;+ requiresInstanceSetup: boolean;+ connectedProjects: number | null;+ }[];+};++async function withEnv<T>(+ values: Record<string, string>,+ run: () => Promise<T>,+): Promise<T> {+ const previous = Object.fromEntries(+ Object.keys(values).map((key) => [key, process.env[key]]),+ );+ Object.assign(process.env, values);+ try {+ return await run();+ } finally {+ for (const [key, value] of Object.entries(previous)) {+ if (value === undefined) delete process.env[key];+ else process.env[key] = value;+ }+ }+}++async function createAdminApiKey(userId: string) {+ const key = `test_${randomUUID()}`;+ await db.insert(schema.apikeyTable).values({+ referenceId: userId,+ userId,+ key: createHash("sha256").update(key).digest("base64url"),+ enabled: true,+ createdAt: new Date(),+ updatedAt: new Date(),+ });+ return key;+}++describe("admin system status", () => {+ it("requires a signed-in instance administrator session", async () => {+ mockAnonymousSession();+ expect((await projectAccessApi()("/admin/system")).status).toBe(401);+ expect(+ (await projectAccessApi()("/admin/system/test-email", { method: "POST" }))+ .status,+ ).toBe(401);++ const ctx = await createRestrictedWorkspace();+ mockAuthenticatedSession(ctx.owner);+ smtp.configured.mockReturnValue(true);+ expect((await projectAccessApi()("/admin/system")).status).toBe(403);+ expect(+ (await projectAccessApi()("/admin/system/test-email", { method: "POST" }))+ .status,+ ).toBe(403);+ expect(smtp.send).not.toHaveBeenCalled();+ });++ it("rejects API keys even when they belong to an administrator", async () => {+ const admin = await createInstanceAdmin();+ const key = await createAdminApiKey(admin.id);+ mockAnonymousSession();+ smtp.configured.mockReturnValue(true);+ const request = projectAccessApi({ "x-api-key": key });++ expect((await request("/admin/system")).status).toBe(403);+ expect(+ (await request("/admin/system/test-email", { method: "POST" })).status,+ ).toBe(403);+ expect(smtp.send).not.toHaveBeenCalled();+ });++ it("reports each service, treating optional ones as not configured", async () => {+ const ctx = await createRestrictedWorkspace();+ const activeProject = ctx.alpha;+ const inactiveProject = ctx.beta;+ await db.insert(schema.integrationTable).values([+ { projectId: activeProject.id, type: "gitea", config: "{}" },+ {+ projectId: inactiveProject.id,+ type: "gitea",+ config: "{}",+ isActive: false,+ },+ { projectId: inactiveProject.id, type: "slack", config: "{}" },+ ]);+ const admin = await createInstanceAdmin();+ mockAuthenticatedSession(admin);++ const response = await projectAccessApi()("/admin/system");++ expect(response.status).toBe(200);+ expect(response.headers.get("cache-control")).toBe("no-store");+ const body = (await response.json()) as SystemStatus;+ const rootPackage = JSON.parse(+ readFileSync(new URL("../../package.json", import.meta.url), "utf8"),+ ) as { version: string };+ expect(body.version).toBe(rootPackage.version);+ expect(body.api.status).toBe("ok");+ expect(body.api.uptimeSeconds).toBeGreaterThanOrEqual(0);+ expect(body.database.status).toBe("ok");+ expect(body.database.serverVersion).toMatch(/^\d+/);+ expect(body.database.migrationsApplied).toBeGreaterThan(0);+ expect(body.redis).toEqual({+ status: "not_configured",+ mode: null,+ errorCode: null,+ });+ expect(body.realtime.connections).toBe(0);+ expect(body.email).toEqual({+ status: "not_configured",+ configured: false,+ errorCode: null,+ });+ expect(body.storage).toEqual({+ status: "not_configured",+ configured: false,+ errorCode: null,+ });+ expect(body.auth.passwordSignIn).toBe(true);+ expect(body.auth.registration).toBe(true);+ expect(body.auth.providers.map((provider) => provider.id)).toEqual([+ "github",+ "google",+ "discord",+ "custom",+ ]);+ expect(+ body.auth.providers.every(+ (provider) => provider.status === "not_configured",+ ),+ ).toBe(true);++ const integrations = new Map(+ body.integrations.map((provider) => [provider.type, provider]),+ );+ expect(integrations.get("gitea")).toMatchObject({+ status: "ok",+ requiresInstanceSetup: false,+ connectedProjects: 1,+ });+ expect(integrations.get("slack")?.connectedProjects).toBe(1);+ expect(integrations.get("github")).toMatchObject({+ status: "not_configured",+ requiresInstanceSetup: true,+ connectedProjects: 0,+ });+ });++ it("never returns configured secrets, and reports unreachable services as down", async () => {+ const secrets = {+ GOOGLE_CLIENT_ID: "google-client-id-value",+ GOOGLE_CLIENT_SECRET: "google-secret-value",+ DISCORD_CLIENT_ID: "discord-client-id-value",+ GITHUB_OAUTH_CLIENT_ID: "github-oauth-id-value",+ GITHUB_OAUTH_CLIENT_SECRET: "github-oauth-secret-value",+ CUSTOM_OAUTH_CLIENT_ID: "oidc-client-id-value",+ CUSTOM_OAUTH_CLIENT_SECRET: "oidc-secret-value",+ CUSTOM_OAUTH_DISCOVERY_URL:+ "https://oidc-user:[email protected]/.well-known/openid-configuration",+ CUSTOM_OAUTH_NAME: "Company SSO",+ GITHUB_APP_ID: "424242",+ GITHUB_WEBHOOK_SECRET: "github-webhook-secret-value",+ GITHUB_PRIVATE_KEY: "github-private-key-value",+ REDIS_URL: "redis://:[email protected]:6379",+ S3_ENDPOINT: "http://127.0.0.1:1",+ S3_BUCKET: "private-bucket-name",+ S3_ACCESS_KEY_ID: "s3-access-key-value",+ S3_SECRET_ACCESS_KEY: "s3-secret-value",+ };+ smtp.configured.mockReturnValue(true);+ smtp.verify.mockResolvedValue({ status: "failed", code: "EAUTH" });+ redis.ping.mockRejectedValue(+ Object.assign(+ new Error(+ "connect ECONNREFUSED redis://:[email protected]",+ ),+ { code: "ECONNREFUSED" },+ ),+ );+ const admin = await createInstanceAdmin();+ mockAuthenticatedSession(admin);++ const response = await withEnv(secrets, () =>+ projectAccessApi()("/admin/system"),+ );++ expect(response.status).toBe(200);+ const text = await response.text();+ for (const [name, value] of Object.entries(secrets)) {+ if (name === "CUSTOM_OAUTH_NAME" || name === "GITHUB_APP_ID") continue;+ expect(text, name).not.toContain(value);+ }+ expect(text).not.toContain("redis.internal.test");+ expect(text).not.toContain("idp.example.test");+ expect(text).not.toContain("127.0.0.1");++ const body = JSON.parse(text) as SystemStatus;+ expect(body.redis).toEqual({+ status: "down",+ mode: "standalone",+ errorCode: "ECONNREFUSED",+ });+ expect(body.realtime.status).not.toBe("ok");+ expect(body.email).toEqual({+ status: "down",+ configured: true,+ errorCode: "EAUTH",+ });+ expect(body.storage).toMatchObject({ status: "down", configured: true });+ expect(body.database.status).toBe("ok");+ const providers = new Map(+ body.auth.providers.map((provider) => [provider.id, provider]),+ );+ expect(providers.get("google")?.status).toBe("ok");+ expect(providers.get("github")?.status).toBe("ok");+ expect(providers.get("discord")?.status).toBe("warning");+ expect(providers.get("custom")).toEqual({+ id: "custom",+ name: "Company SSO",+ status: "ok",+ });+ expect(+ body.integrations.find((provider) => provider.type === "github")?.status,+ ).toBe("ok");+ });+});++describe("admin test email", () => {+ it("explains that SMTP is not configured without trying to send", async () => {+ const admin = await createInstanceAdmin();+ mockAuthenticatedSession(admin);++ const response = await projectAccessApi()("/admin/system/test-email", {+ method: "POST",+ });++ expect(response.status).toBe(409);+ expect(await response.json()).toMatchObject({+ code: "SMTP_NOT_CONFIGURED",+ });+ expect(smtp.send).not.toHaveBeenCalled();+ });++ it("only ever sends to the calling administrator", async () => {+ smtp.configured.mockReturnValue(true);+ const admin = await createInstanceAdmin();+ mockAuthenticatedSession(admin);++ const response = await projectAccessApi()("/admin/system/test-email", {+ method: "POST",+ body: { to: "[email protected]", email: "[email protected]" },+ });++ expect(response.status).toBe(200);+ expect(await response.json()).toEqual({ sent: true, to: admin.email });+ expect(smtp.send).toHaveBeenCalledTimes(1);+ expect(smtp.send.mock.calls[0]?.[0]).toBe(admin.email);+ const calls = JSON.stringify(smtp.send.mock.calls);+ expect(calls).not.toContain("someone-else@");+ expect(calls).not.toContain("victim@");+ });++ it("returns a safe error when the mail server rejects the message", async () => {+ smtp.configured.mockReturnValue(true);+ smtp.send.mockRejectedValue(+ Object.assign(+ new Error(+ "535 Authentication failed for smtp-user:smtp-password-value",+ ),+ { code: "EAUTH", responseCode: 535 },+ ),+ );+ vi.spyOn(console, "error").mockImplementation(() => {});+ const admin = await createInstanceAdmin();+ mockAuthenticatedSession(admin);++ const response = await projectAccessApi()("/admin/system/test-email", {+ method: "POST",+ });++ expect(response.status).toBe(502);+ const text = await response.text();+ expect(text).toContain("EAUTH 535");+ expect(text).not.toContain("smtp-password-value");+ expect(JSON.stringify(vi.mocked(console.error).mock.calls)).not.toContain(+ "smtp-password-value",+ );+ });++ it("limits how often one administrator can send", async () => {+ smtp.configured.mockReturnValue(true);+ const admin = await createInstanceAdmin();+ mockAuthenticatedSession(admin);+ const request = projectAccessApi();++ for (let attempt = 0; attempt < 5; attempt++) {+ expect(+ (await request("/admin/system/test-email", { method: "POST" })).status,+ ).toBe(200);+ }+ const limited = await request("/admin/system/test-email", {+ method: "POST",+ });++ expect(limited.status).toBe(429);+ expect(Number(limited.headers.get("retry-after"))).toBeGreaterThan(0);+ expect(await limited.json()).toMatchObject({ code: "RATE_LIMITED" });+ expect(smtp.send).toHaveBeenCalledTimes(5);+ });+});diff --git a/tests/api-integration/mocks/email.ts b/tests/api-integration/mocks/email.tsindex 3aaad14ea..15634e3c9 100644--- a/tests/api-integration/mocks/email.ts+++ b/tests/api-integration/mocks/email.ts@@ -1,6 +1,8 @@import type { EmailResult } from "../../../packages/email/src/send-email";+import type { SmtpVerification } from "../../../packages/email/src/verify-smtp-connection";export { OTP_EXPIRY_SECONDS } from "../../../packages/email/src/otp-expiry";+export { getSmtpErrorDetails } from "../../../packages/email/src/smtp-error-details";export async function sendMagicLinkEmail(_to: string,@@ -53,3 +55,17 @@ export async function sendEmailVerificationEmail(): Promise<EmailResult> {return { success: true };}++export async function sendTestEmail(+ _to: string,+ _subject: string,+ _data: unknown,+): Promise<EmailResult> {+ return { success: false, reason: "SMTP_NOT_CONFIGURED" };+}++export async function verifySmtpConnection(+ _timeoutMs: number,+): Promise<SmtpVerification> {+ return { status: "not_configured" };+}